From 3cc22eed44b519c23fba2e2d32314c56d17c1b7b Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Thu, 14 Jul 2011 19:50:21 -0400
Subject: [PATCH] Add some GtkAccessible documentation

Describe the current thinking about how to provide
3rd party accessible implementations.
---
 gtk/gtkaccessible.c | 36 ++++++++++++++++++++++--------------
 gtk/gtkaccessible.h | 23 ++++++++++-------------
 2 files changed, 32 insertions(+), 27 deletions(-)

diff --git a/gtk/gtkaccessible.c b/gtk/gtkaccessible.c
index 25f1c94f54..161ab734ce 100644
--- a/gtk/gtkaccessible.c
+++ b/gtk/gtkaccessible.c
@@ -28,13 +28,20 @@
  * SECTION:gtkaccessible
  * @Short_description: Accessibility support for widgets
  * @Title: GtkAccessible
+ *
+ * The #GtkAccessible class is the base class for accessible
+ * implementations for #GtkWidget subclasses. It is a thin
+ * wrapper around #AtkObject, which adds facilities for associating
+ * a widget with its accessible object.
+ *
+ * An accessible implementation for a third-party widget should
+ * derive from #GtkAccessible and implement the suitable interfaces
+ * from ATK, such as #AtkText or #AtkSelection. To establish
+ * the connection between the widget class and its corresponding
+ * acccessible implementation, override the get_accessible vfunc
+ * in #GtkWidgetClass.
  */
 
-/*
- * GtkAccessiblePriv:
- * @widget: The GtkWidget whose properties and features are exported via this
- *   accessible instance
- */
 struct _GtkAccessiblePrivate
 {
   GtkWidget *widget;
@@ -68,7 +75,7 @@ gtk_accessible_class_init (GtkAccessibleClass *klass)
  * Sets the #GtkWidget corresponding to the #GtkAccessible.
  *
  * Since: 2.22
- **/
+ */
 void
 gtk_accessible_set_widget (GtkAccessible *accessible,
                            GtkWidget     *widget)
@@ -82,14 +89,15 @@ gtk_accessible_set_widget (GtkAccessible *accessible,
  * gtk_accessible_get_widget:
  * @accessible: a #GtkAccessible
  *
- * Gets the #GtkWidget corresponding to the #GtkAccessible. The returned widget
- * does not have a reference added, so you do not need to unref it.
+ * Gets the #GtkWidget corresponding to the #GtkAccessible.
+ * The returned widget does not have a reference added, so
+ * you do not need to unref it.
  *
- * Returns: (transfer none): pointer to the #GtkWidget corresponding to
- *   the #GtkAccessible, or %NULL.
+ * Returns: (transfer none): pointer to the #GtkWidget
+ *     corresponding to the #GtkAccessible, or %NULL.
  *
  * Since: 2.22
- **/
+ */
 GtkWidget*
 gtk_accessible_get_widget (GtkAccessible *accessible)
 {
@@ -99,11 +107,11 @@ gtk_accessible_get_widget (GtkAccessible *accessible)
 }
 
 /**
- * gtk_accessible_connect_widget_destroyed
+ * gtk_accessible_connect_widget_destroyed:
  * @accessible: a #GtkAccessible
  *
- * This function specifies the callback function to be called when the widget
- * corresponding to a GtkAccessible is destroyed.
+ * This function specifies the callback function to be called
+ * when the widget corresponding to a GtkAccessible is destroyed.
  */
 void
 gtk_accessible_connect_widget_destroyed (GtkAccessible *accessible)
diff --git a/gtk/gtkaccessible.h b/gtk/gtkaccessible.h
index d3a154e7ed..04d213a3a3 100644
--- a/gtk/gtkaccessible.h
+++ b/gtk/gtkaccessible.h
@@ -36,13 +36,10 @@ G_BEGIN_DECLS
 #define GTK_IS_ACCESSIBLE_CLASS(klass)       (G_TYPE_CHECK_CLASS_TYPE ((klass), GTK_TYPE_ACCESSIBLE))
 #define GTK_ACCESSIBLE_GET_CLASS(obj)        (G_TYPE_INSTANCE_GET_CLASS ((obj), GTK_TYPE_ACCESSIBLE, GtkAccessibleClass))
 
-typedef struct _GtkAccessible                GtkAccessible;
-typedef struct _GtkAccessiblePrivate         GtkAccessiblePrivate;
-typedef struct _GtkAccessibleClass           GtkAccessibleClass;
+typedef struct _GtkAccessible        GtkAccessible;
+typedef struct _GtkAccessiblePrivate GtkAccessiblePrivate;
+typedef struct _GtkAccessibleClass   GtkAccessibleClass;
 
-  /*
-   * This object is a thin wrapper, in the GTK+ namespace, for AtkObject
-   */
 struct _GtkAccessible
 {
   AtkObject parent;
@@ -55,8 +52,8 @@ struct _GtkAccessibleClass
 {
   AtkObjectClass parent_class;
 
-  void (*connect_widget_destroyed)              (GtkAccessible     *accessible);
-  
+  void (*connect_widget_destroyed) (GtkAccessible *accessible);
+
   /* Padding for future expansion */
   void (*_gtk_reserved1) (void);
   void (*_gtk_reserved2) (void);
@@ -64,12 +61,12 @@ struct _GtkAccessibleClass
   void (*_gtk_reserved4) (void);
 };
 
-GType gtk_accessible_get_type (void) G_GNUC_CONST;
+GType      gtk_accessible_get_type                 (void) G_GNUC_CONST;
 
-void        gtk_accessible_set_widget                  (GtkAccessible     *accessible,
-                                                        GtkWidget         *widget);
-GtkWidget*  gtk_accessible_get_widget                  (GtkAccessible     *accessible);
-void        gtk_accessible_connect_widget_destroyed    (GtkAccessible     *accessible);
+void       gtk_accessible_set_widget               (GtkAccessible *accessible,
+                                                    GtkWidget     *widget);
+GtkWidget *gtk_accessible_get_widget               (GtkAccessible *accessible);
+void       gtk_accessible_connect_widget_destroyed (GtkAccessible *accessible);
 
 G_END_DECLS
 
-- 
2.30.2